Expand description
Safe, Fast, and user-friendly wrapper around the CUDA Driver API.
Low level CUDA interop
Because additions to CUDA and libraries that use CUDA are everchanging, this library
provides unsafe functions for retrieving and setting handles to raw cuda_sys objects.
This allows advanced users to embed libraries that rely on CUDA, such as OptiX. We
also re-export cuda_sys as a sys module for convenience.
CUDA Terminology:
Devices and Hosts:
This crate and its documentation uses the terms “device” and “host” frequently, so it’s worth explaining them in more detail. A device refers to a CUDA-capable GPU or similar device and its associated external memory space. The host is the CPU and its associated memory space. Data must be transferred from host memory to device memory before the device can use it for computations, and the results must then be transferred back to host memory.
Contexts, Modules, Streams and Functions:
A CUDA context is akin to a process on the host - it contains all of the state for working with a device, all memory allocations, etc. Each context is associated with a single device.
A Module is similar to a shared-object library - it is a piece of compiled code which exports functions and global values. Functions can be loaded from modules and launched on a device as one might load a function from a shared-object file and call it. Functions are also known as kernels and the two terms will be used interchangeably.
A Stream is akin to a thread - asynchronous work such as kernel execution can be queued into a stream. Work within a single stream will execute sequentially in the order that it was submitted, and may interleave with work from other streams.
Grids, Blocks and Threads:
CUDA devices typically execute kernel functions on many threads in parallel. These threads can be grouped into thread blocks, which share an area of fast hardware memory known as shared memory. Thread blocks can be one-, two-, or three-dimensional, which is helpful when working with multi-dimensional data such as images. Thread blocks are then grouped into grids, which can also be one-, two-, or three-dimensional.
CUDA devices often contain multiple separate processors. Each processor is capable of excuting many threads simultaneously, but they must be from the same thread block. Thus, it is important to ensure that the grid size is large enough to provide work for all processors. On the other hand, if the thread blocks are too small each processor will be under-utilized and the code will be unable to make effective use of shared memory.
Usage:
Before using cust, you must install the CUDA development libraries for your system. Version 9.0 or newer is required. You must also have a CUDA-capable GPU installed with the appropriate drivers.
Cust will try to find the CUDA libraries automatically, if it is unable to find it, you can set
CUDA_LIBRARY_PATH to some path manually.
Re-exports
pub use cust_raw as sys;Modules
CUDA Context handling.
Functions and types for enumerating CUDA devices and retrieving information about them.
Types for error handling
Events can be used to track status and dependencies, as well as to measure the duration of work submitted to a CUDA stream.
External memory and synchronization resources
Functions and types for working with CUDA kernels.
Functions for linking together multiple PTX files into a module.
Access to CUDA’s memory allocation and transfer functions.
Functions and types for working with CUDA modules.
This module re-exports a number of commonly-used types for working with cust.
Streams of work for the device to perform.
Macros
Creates a kernel invocation using the same syntax as launch to be used to insert kernel launches inside graphs.
This returns a Result of a kernel invocation object you can then pass to a graph.
Launch a kernel function asynchronously.
Structs
Struct representing the CUDA API version number.
Bit flags for initializing the CUDA driver. Currently, no flags are defined,
so CudaFlags::empty() is the only valid value.
Functions
Initialize the CUDA Driver API.
Shortcut for initializing the CUDA Driver API and creating a CUDA context with default settings for the first device.